Skip to main content

First Steps

You've installed web3agent and configured your AI host. This page walks through a handful of commands to verify everything is working and get familiar with what's available.

Check server status

The first thing to verify is that the server starts and reports a healthy state.

npx web3agent tool call server_status --input '{}' --json

Expected output:

{
  "ok": true,
  "data": {
    "version": "0.4.0",
    "toolCount": 107,
    "defaultChain": "base",
    "walletConnected": false
  }
}

walletConnected: false is expected if you haven't set PRIVATE_KEY yet. Read-only tools (market data, explorer, token resolution) work without a wallet. Write tools (swaps, transfers, contract writes) require one.

If toolCount is 0 or the command errors, check that Node.js 22+ is on your PATH and that your environment variables are set correctly.

List supported chains

See all 17 chains web3agent supports, with their chain IDs and native token symbols.

npx web3agent tool call list_supported_chains --input '{}' --json

{
  "ok": true,
  "data": {
    "chains": [
      { "id": 8453, "name": "base", "nativeCurrency": "ETH" },
      { "id": 1, "name": "ethereum", "nativeCurrency": "ETH" },
      { "id": 42161, "name": "arbitrum", "nativeCurrency": "ETH" },
      { "id": 137, "name": "polygon", "nativeCurrency": "MATIC" }
      // ... 13 more
    ],
    "default": 8453
  }
}

Resolve a token

Token resolution maps a symbol to its canonical contract address on a given chain. This is one of the most commonly used tools.

npx web3agent tool call resolve_token \
  --input '{"symbol":"USDC","chainId":8453}' \
  --json

{
  "ok": true,
  "data": {
    "symbol": "USDC",
    "name": "USD Coin",
    "address": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "decimals": 6,
    "chainId": 8453
  }
}

Try a few more to get a feel for the resolver:

# WETH on Base
npx web3agent tool call resolve_token \
  --input '{"symbol":"WETH","chainId":8453}' \
  --json

# USDC on Arbitrum
npx web3agent tool call resolve_token \
  --input '{"symbol":"USDC","chainId":42161}' \
  --json

# DAI on Ethereum mainnet
npx web3agent tool call resolve_token \
  --input '{"symbol":"DAI","chainId":1}' \
  --json

List available tools

Get the full list of tools web3agent exposes, with their names and descriptions.

npx web3agent tools list --json

The output is a JSON array of tool objects. Each has a name, description, and riskLevel (safe, financial, or destructive).

To filter by prefix and see just the Orbs tools:

npx web3agent tools list --json | grep '"name"' | grep orbs

To see just the explorer tools:

npx web3agent tools list --json | grep '"name"' | grep blockscout

Inspect a specific tool

Get the full schema for any tool, including all input parameters and their types.

npx web3agent tools describe resolve_token --json

{
  "name": "resolve_token",
  "description": "Resolve a token symbol or address to its canonical metadata on a given chain.",
  "riskLevel": "safe",
  "inputSchema": {
    "type": "object",
    "properties": {
      "symbol": {
        "type": "string",
        "description": "Token symbol (e.g. USDC, WETH, DAI)"
      },
      "address": {
        "type": "string",
        "description": "Token contract address (alternative to symbol)"
      },
      "chainId": {
        "type": "number",
        "description": "Chain ID. Defaults to CHAIN_ID env var (8453 = Base)."
      }
    }
  }
}

This is useful when you want to understand exactly what a tool expects before calling it from code or from an AI agent.

Run diagnostics

The doctor command checks your environment and reports any issues.

npx web3agent doctor --json

{
  "ok": true,
  "data": {
    "nodeVersion": "22.4.0",
    "nodeVersionOk": true,
    "walletConfigured": false,
    "defaultChain": 8453,
    "chainReachable": true,
    "rpcLatencyMs": 142,
    "apiKeys": {
      "etherscan": false,
      "lifi": false,
      "zerox": false,
      "coingecko": false
    }
  }
}

The diagnostics check:

  • Node.js version (must be 22+)
  • Whether a wallet is configured (PRIVATE_KEY or MNEMONIC)
  • Whether the default chain's RPC is reachable and how fast it responds
  • Which optional API keys are present

apiKeys entries showing false aren't errors. They just mean those integrations will use public rate-limited endpoints instead of authenticated ones.

Try a read-only tool (no wallet needed)

Market data tools work without a wallet. Get the current price of ETH:

npx web3agent tool call get_token_price \
  --input '{"tokens":["8453:0x4200000000000000000000000000000000000006"]}' \
  --json

The token identifier format is chainId:address. The address above is WETH on Base.

{
  "ok": true,
  "data": {
    "prices": {
      "8453:0x4200000000000000000000000000000000000006": {
        "usd": 3142.50,
        "usd_24h_change": 1.23
      }
    }
  }
}

Try a wallet-required tool

If you've set PRIVATE_KEY, try getting your wallet's native balance:

PRIVATE_KEY=0x... npx web3agent tool call evm_get_balance \
  --input '{"chainId":8453}' \
  --json

{
  "ok": true,
  "data": {
    "address": "0xYourAddress",
    "balance": "0.05",
    "balanceRaw": "50000000000000000",
    "symbol": "ETH",
    "chainId": 8453
  }
}

What to explore next

Now that you've verified the installation, here are the natural next areas to dig into:

Core concepts

  • How the confirmation queue works for write operations
  • How the policy engine enforces spend limits
  • How to use the programmatic SDK in TypeScript

Integrations

  • Orbs Protocol: swaps, TWAP orders, limit orders, stop-loss, take-profit
  • LI.FI: cross-chain bridges with fee and time estimates
  • Blockscout: indexed blockchain data (transactions, tokens, contracts, NFTs)
  • EVM tools: contract reads and writes, ENS resolution, gas estimation

Agentic economy

  • ACP: create and manage agent cooperation jobs
  • aGDP: hire agents and publish offerings on the Virtuals marketplace
  • ERC-8004: register your agent's on-chain identity
  • X-402: HTTP-native stablecoin payments

Once your AI host is configured (via npx web3agent init), you don't need to call tools from the CLI. Your AI agent calls them directly. The CLI is useful for testing, scripting, and debugging.